{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0df2aeab",
   "metadata": {},
   "source": [
    "# How is ``brainpy`` different from other frameworks?\n",
    "\n",
    "[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/brainpy/brainpy/blob/master/docs_version2/tutorial_FAQs/uniqueness_of-brainpy-math.ipynb)\n",
    "[![Open in Kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://github.com/brainpy/brainpy/blob/master/docs_version2/tutorial_FAQs/uniqueness_of-brainpy-math.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "499d521c",
   "metadata": {},
   "source": [
    "@[Chaoming Wang](https://github.com/chaoming0625)\n",
    "@[Xiaoyu Chen](mailto:c-xy17@tsinghua.org.cn)"
   ]
  },
  {
   "cell_type": "code",
   "id": "5fdb1409",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-10-06T03:59:07.508431Z",
     "start_time": "2025-10-06T03:59:03.180452Z"
    }
   },
   "source": [
    "import brainpy as bp\n",
    "import brainpy.math as bm\n",
    "\n",
    "bp.math.set_platform('cpu')\n",
    "\n",
    "bp.__version__"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'3.0.0'"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 1
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "## BrainPy vs Brian2/NEST/NEURON ..."
   ],
   "id": "a36d92625dddcacd"
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "Different from traditional brain simulators (most of them employ a descriptive language for programming brain dynamics models), BrainPy aims to provide the full supports for brain dynamics modeling.\n",
    "\n",
    "Currently, brain dynamics modeling is far beyond *simulation*. There are many new modeling approaches which take inspiration from the machine learning community. Moreover, it has also inspired the new development of brain-inspired computation.\n",
    "\n",
    "These new advances cannot be captured by the traditional brain simulators. Therefore, BrainPy aims to provide an ecosystem for brain dynamics modeling, in which users can build various models easily and flexibly, and extend new modeling approach conveniently, etc.\n",
    "\n",
    "The core idea behind BrainPy is the Just-In-Time (JIT) compilation. JIT compilation enables your Python code to be compiled into machine code \"just-in-time\" for execution. Subsequently, such transformed code can run at native machine code speed!\n",
    "\n",
    "Based on this, BrainPy provides an integrated platform for brain dynamics modeling, including\n",
    "\n",
    "- universal model building\n",
    "- dynamics simulation\n",
    "- dynamics training\n",
    "- dynamics analysis\n",
    "\n",
    "Such integrative framework may help users to study brain dynamics comprehensively."
   ],
   "id": "e8ff9e3a46351874"
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "## BrainPy vs JAX/Numba"
   ],
   "id": "4c6d015a64a6f0b4"
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "BrainPy relies on [JAX](https://github.com/google/jax) and [Numba](https://github.com/numba/numba). But it also has important aspects which are different from them.\n",
    "\n",
    "JAX and Numba are excellent JIT compilers in Python. However, they are designed to work only on [pure Python functions](https://en.wikipedia.org/wiki/Pure_function).\n",
    "Most computational neuroscience models have too many parameters and variables to manage using functions only. Therefore, BrainPy provides an object-oriented programming interface for brain dynamics modeling. There object-oriented transformations are implemented in ``brainpy.math`` module.\n",
    "\n",
    "``brainpy.math`` is not intended to be a reimplementation of the API of any other frameworks. All we are trying to do is to make **a better brain dynamics programming framework for Python users**.\n",
    "\n",
    "There are important differences between ``brainpy.math`` and  JAX and JAX related frameworks."
   ],
   "id": "1bf82e3f7c74e39d"
  },
  {
   "cell_type": "markdown",
   "id": "56bff518",
   "metadata": {},
   "source": [
    "Specifically, ``brainpy.math`` provides:\n",
    "\n",
    "1. **Numpy-like ndarray**.\n",
    "\n",
    "Python users are familiar with [NumPy](https://numpy.org/), especially its [ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html). JAX has similar ``ndarray`` structures and operations. However, several basic features are fundamentally different from numpy ndarray. For example, JAX ndarray does not support in-place mutating updates, like ``x[i] += y``. To overcome these drawbacks, ``brainpy.math`` provides ``Array`` that can be used in the same way as numpy ndarray."
   ]
  },
  {
   "cell_type": "code",
   "id": "c58daa91",
   "metadata": {
    "scrolled": true,
    "ExecuteTime": {
     "end_time": "2025-10-06T03:59:07.532858Z",
     "start_time": "2025-10-06T03:59:07.512563Z"
    }
   },
   "source": [
    "b = bm.arange(5)\n",
    "b"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Array(value=Array([0, 1, 2, 3, 4]), dtype=int32)"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 2
  },
  {
   "cell_type": "code",
   "id": "7d2a1bdb",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-10-06T03:59:07.629279Z",
     "start_time": "2025-10-06T03:59:07.537502Z"
    }
   },
   "source": [
    "b[0] += 5\n",
    "b"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Array(value=Array([5, 1, 2, 3, 4]), dtype=int32)"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 3
  },
  {
   "cell_type": "markdown",
   "id": "627fd723",
   "metadata": {},
   "source": [
    "2. **Numpy-like random sampling**.\n",
    "\n",
    "JAX has its own style to make random numbers, which is very different from the original NumPy. To provide a consistent experience, ``brainpy.math`` provides ``brainpy.math.random`` for random sampling just like the ``numpy.random`` module. For example:"
   ]
  },
  {
   "cell_type": "code",
   "id": "cdba27e2",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-10-06T03:59:07.659123Z",
     "start_time": "2025-10-06T03:59:07.632870Z"
    }
   },
   "source": [
    "# random sampling in \"brainpy.math.random\"\n",
    "\n",
    "bm.random.seed(12345)"
   ],
   "outputs": [],
   "execution_count": 4
  },
  {
   "cell_type": "code",
   "id": "bfb052e0",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-10-06T03:59:07.889126Z",
     "start_time": "2025-10-06T03:59:07.699315Z"
    }
   },
   "source": [
    "bm.random.random(5)"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Array([0.6526346 , 0.5099158 , 0.86456275, 0.90409184, 0.86582637],      dtype=float32)"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 5
  },
  {
   "cell_type": "code",
   "id": "e63f7e41",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-10-06T03:59:08.026336Z",
     "start_time": "2025-10-06T03:59:07.896188Z"
    }
   },
   "source": [
    "bm.random.normal(0., 2., 5)"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Array([-1.085594 , -3.2041652, -2.427458 , -3.2681167, -1.5416642],      dtype=float32)"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 6
  },
  {
   "cell_type": "markdown",
   "id": "81903ff6",
   "metadata": {},
   "source": [
    "For more details, please see the [Arrays](./array.ipynb) tutorial."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9af9e385",
   "metadata": {},
   "source": [
    "3. **JAX transformations on class objects**.\n",
    "\n",
    "OOP is the essence of Python. However, JAX's excellent tranformations (like JIT compilation) only support [pure functions](https://en.wikipedia.org/wiki/Pure_function). To make them work on object-oriented coding in brain dynamics programming, ``brainpy.math`` extends JAX transformations to Python classes. Details please see [BrainPy Concept of Object-oriented Transformation](../core_concept/brainpy_transform_concept.ipynb).\n",
    "\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.7"
  },
  "latex_envs": {
   "LaTeX_envs_menu_present": true,
   "autoclose": false,
   "autocomplete": true,
   "bibliofile": "biblio.bib",
   "cite_by": "apalike",
   "current_citInitial": 1,
   "eqLabelWithNumbers": true,
   "eqNumInitial": 1,
   "hotkeys": {
    "equation": "Ctrl-E",
    "itemize": "Ctrl-I"
   },
   "labels_anchors": false,
   "latex_user_defs": false,
   "report_style_numbering": false,
   "user_envs_cfg": false
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
